<HTML>
<HEAD>
   <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
   <META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (Win95; I) [Netscape]">
   <META NAME="Author" CONTENT="John Thomas">
   <TITLE>TSpaces Whiteboard PlugIn Demo</TITLE>
<!-- 
    wb_plugin.html

    This page will setup to run the TSpaces Whiteboard Demo applet
    using the Java PlugIn
             
   -->


</HEAD>
<! Set blue background with red and purple links ->
<BODY TEXT="#000000" BGCOLOR="#99CCCC" LINK="#CC0000" VLINK="#330099" ALINK="#FF3300">
<! Include the Masthead ->
<CENTER><IMG SRC="gifs/masthead.gif" ALT="Research" BORDER=0 HEIGHT=92 WIDTH=480 ALIGN=CENTER></CENTER>

 
<CENTER>
<H1>
<FONT COLOR="#000066">TSpaces Whiteboard PlugIn Demo</FONT></H1></CENTER>

<P>This demo application uses the Java PlugIn support to show how easy it is to code 
a multi-user application using TSpaces.  Refer to the 
<a href=#programming>programming details below</a>.
<P>

<!--"CONVERTED_APPLET"-->
<!-- CONVERTER VERSION 1.0 -->
<OBJECT classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
WIDTH = 400 HEIGHT = 300 ALIGN = "baseline"  codebase="http://java.sun.com/products/plugin/1.2/jinstall-12-win32.cab#Version=1,2,0,0">
<PARAM NAME = CODE VALUE = com.ibm.tspaces.examples.whiteboard.Whiteboard.class >
<PARAM NAME = CODEBASE VALUE = "../classes" >
<PARAM NAME = ARCHIVE VALUE = "../lib/tspaces_client.jar" >

<PARAM NAME="type" VALUE="application/x-java-applet;version=1.2">
<COMMENT>
<EMBED type="application/x-java-applet;version=1.2" java_CODE = com.ibm.tspaces.examples.whiteboard.Whiteboard.class java_CODEBASE = "../classes" java_ARCHIVE = "../lib/tspaces_client.jar" WIDTH = 400 HEIGHT = 300 ALIGN = "baseline"   pluginspage="http://java.sun.com/products/plugin/1.2/plugin-install.html"><NOEMBED></COMMENT>

</NOEMBED></EMBED>
</OBJECT>

<!--
<APPLET  CODE = com.ibm.tspaces.examples.whiteboard.Whiteboard.class CODEBASE = "../classes" ARCHIVE = "../lib/tspaces_client.jar" WIDTH = 400 HEIGHT = 300 ALIGN = "baseline" >


</APPLET>
-->
<!--"END_CONVERTED_APPLET"-->


<CENTER>
<HR></CENTER>

<CENTER>&nbsp;</CENTER>

<H2>
Operation:</H2>

<UL>Select one of the colors with the color button and select either "Lines"
or "Points" from the menu.

<P>Use the Mouse to draw 1 or more lines or sets of points.

<P>Press "Publish" to send your masterpiece to everyone else that is running
the demo.
<P>Press "Erase" to erase the lines that you drew since the last Publish.
<P>Press "EraseALL" to erase the all the Whiteboards. <B><FONT SIZE=+1>Note: </FONT>This
will erase everyone's whiteboard, not just yours!</B>
<BR>&nbsp;</UL>


<SCRIPT language=javascript>
<!-- Hide javascript from old browsers
      	


<CENTER>
<HR></CENTER>

<H2>
<B>TSpaces Server Interface</B></H2>

<UL>The TSpaces Server contains a built-in HTTP Server that can be used
by the developer of a TSpaces application to query the status of the
server via a Web Browser interface. Using this interface, you can query
the current status of the server, view the Tuples that are stored at the
server and issue various Administrator commands. Although some of these
functions are disabled in the our online demo, you can access the rest of these
features by selecting the link below.
<H2>
<B>

<SCRIPT language=javascript>
<!-- Hide javascript from old browsers
  // Put the current server into the URL along with the special HTTP Port
  aText = '<A HREF="http://'"
  if ( location.hostname == "" ) 
    aText += "localhost" 
  else
    aText += location.hostname
  aText += ':8201/debug">TSpaces Server HTTP Interface</A>'"
     
  document.write (aText + "<p>")                           
  // end hiding -->
</SCRIPT>
</B></H2>
</UL>

<CENTER>
<HR></CENTER>
<a name=programming></a>
<H2>
<B>TSpaces Programming Details:</B></H2>

<UL>The Java source code for the Whiteboard is available. There
are 3 Java files:
<UL>
<LI>
<B>Whiteboard.java</B></LI>

<LI>
<B>WhiteboardPanel.java</B></LI>

<LI>
<B>WhiteboardControls.java</B></LI>
</UL>
All of the TSpaces related code is contained in the file
<A HREF="../examples/whiteboard/WhiteboardPanel.java"><B>WhiteboardPanel.java</A></B>.
The following shows the TSpaces code along with comments describing
the purpose of the code and links to the related JavaDoc documentation.  
Refer to actual code to see it in context.  You may also refer to the 
<a href=progrguide.html>TSpaces Programmer's Guide</a> for more information.
</UL>

<H3>
<B>Initialization</B></H3>

<UL>
For initialization, we want to contact the server and tell it that we are interested 
in all Whiteboard lines that are drawn by other users.  We also want to read the 
current status of the Whiteboard.
<p>
<PRE><B>

TupleSpace.appletEnvironment(true);

TupleSpace TSServer;
TSServer = new TupleSpace("Whiteboard", Host,Port);
</B></PRE>
The <b>appletEnvironment(true)</b> statement indicates that this is an applet environment,
We then call the TupleSpace constructor which will access
the <A HREF="javadoc/com.ibm.tspaces.TupleSpace.html">TupleSpace
</A>named "Whiteboard" on the indicated Host:Port. If the TupleSpace does
not exist, it will be created.</UL>

<UL>
<B><PRE>
Tuple match = new Tuple("Whiteboard", 
    			new Field(Vector.class),
    			new Field(Vector.class) );
</PRE></B>
This creates a <A HREF="javadoc/com.ibm.tspaces.SuperTuple.html">Tuple</A>
template object that will be used to match requests that we are interested
in. This template indicates that we are interested in tuples that have 3 
<A HREF="javadoc/com.ibm.tspaces.Field.html">Field</A>s.
The first contains a String equal to "Whiteboard" and the 2nd
and 3rd fields contain Vector object references.</B></UL>

<UL>
<PRE><B>
int seqNum = TSServer.eventRegister(TupleSpace.WRITE,match, this);
</B></PRE>
The <A HREF="javadoc/com.ibm.tspaces.TupleSpace.html#eventRegister">
eventRegister()</a> method indicates the TupleSpace operation that we
are interested in and the template that the related Tuple must match. The
3rd parameter is a Callback object that has a call() method that will be
given control when the event occurs. In this case, the current class implements
the Callback interface and is given control 
when anyone writes a matching Tuple to TSpaces.

<PRE><B>
Tuple tupleSet = TSServer.scan(match);
if ( tupleSet != null) {
   Enumeration e = tupleSet.fields();    
   while (e.hasMoreElements() ) { 
       Field f = (Field)e.nextElement();
       Tuple tuple = (Tuple)f.getValue();
       lines = (Vector)tuple.getField(1).getValue();
       colors = (Vector)tuple.getField(2).getValue();
       ...
   }
}
</B></PRE>
Because TSpaces is a database, it has stored all the line and color Vectors that
have been generated by other users.
So during initialization, we will read all the current line and color
Vectors stored at the TSpaces server. The first line above issues the 
<A HREF="javadoc/com.ibm.tspaces.TupleSpace.html#scan">
scan </A>request to the tupleSpace using the template from earlier. This returns
a tuple whose fields are each tuples, one for each tuple that matched the
template. 
The <A HREF="javadoc/com.ibm.tspaces.SuperTuple.html#fields">
fields()</a> method returns an enumeration that can be
followed to access each individual Tuple. Once the individual Tuple is
accessed, the 
<A HREF="javadoc/com.ibm.tspaces.SuperTuple.html#getField">getField(int)</a>.
<A HREF="javadoc/com.ibm.tspaces.Field.html#value">getValue()</a>
method is used to access the line and color
Vectors from the 2nd and 3rd field. The Vectors are then used to paint
the initial contents of the panel.
</UL>

<H3>
<B>Publish</B></H3>

<UL>
<PRE><B>
try {
   Tuple publish = new Tuple("Whiteboard", linesNew, colorsNew);
   TSServer.write(publish);
} catch(TupleSpaceException tse) {
   System.out.println("TupleSpaceException: " + tse.getMessage());
}
</B></PRE>
When the user presses the Publish button, the collection of user actions
since the last publish are contained in the "linesNew" and "colorsNew"
Vector objects. A Tuple is created with "WhiteSpace" as the 1st field and
Vector references as the 2nd and 3rd Field. 
The <A HREF="javadoc/com.ibm.tspaces.TupleSpace.html#write">write(tuple)</a>
command is then used to write the tuple to the TupleSpace. 
<p>
Note that the typical "try{} catch (TupleSpaceException tse) {}" 
blocks are included here. Although they were not shown earlier,
catching <A HREF="javadoc/com.ibm.tspaces.TupleSpaceException.html">TupleSpaceException</a>
is required for all TSpaces operations.
</UL>

<H3>
<B>Callback Interface</B></H3>

<UL>
<PRE><B>
public class WhiteboardPanel extends Panel 
     implements MouseListener, MouseMotionListener, Callback {

  public synchronized boolean 
  call(String eventName_, String tsName_, int sequenceNumber_, SuperTuple tuple_, boolean isException_) {

     try {
        lines = (Vector)tuple_.getField(1).getValue();
        colors = (Vector)tuple_.getField(2).getValue();
     }  catch(TupleSpaceException tse) {
        ...
        return false;
     }
     ... process 
     return false;
  }
}
</B></PRE>
The registerEvent method described earlier, gave this class as the 
<A HREF=".javadoc/com.ibm.tspaces.Callback.html">Callback</A>
object that was responsible for processing the events. So the class statement
for WhiteboardPanel states that it implements the Callback interface. The
Callback interface requires the implementation of a 
<A HREF="javadoc/com.ibm.tspaces.Callback.html#call">call</A>
method that is shown above. The call method is passed the Tuple that
was written to TupleSpace so that all that is needed is to process the
fields of the Tuple.
</UL>

<H3>
<B>EraseAll</B></H3>


<UL>
The only thing we have left to do is support the <B>EraseAll</B> button.
<PRE><B>
    	
try {
   linesNew = new Vector(20);
   colorsNew = new Vector(20);     	
   TSServer.write("Whiteboard", linesNew, colorsNew);
        	
   TSServer.deleteAll();
        
}  catch(TupleSpaceException tse) {
   ...
}

</B></PRE>
This sends an empty vector to the other clients as a signal that an erase 
has occurred and then deletes all the stored Tuples from the database.
</UL>

<p><hr><p>
The above is all of the TSpaces code that is required to support both 
the network and database requirements for a multi-client application.  
multi-client application.  

</BODY>
</HTML>